The keyv npm package is a simple key-value storage with support for multiple backends. It is designed to be a straightforward solution for key-value storage across different systems and protocols. It supports TTL based expiry, making it suitable for applications like caching and session storage.
Simple Key-Value Storage
Store and retrieve data using simple key-value pairs.
{"const Keyv = require('keyv');
const keyv = new Keyv();
keyv.set('foo', 'bar').then(() => keyv.get('foo').then(value => console.log(value)));
// Logs: 'bar'"}Namespaces
Use namespaces to avoid key collisions when sharing the same storage backend.
{"const Keyv = require('keyv');
const users = new Keyv('sqlite://path/to/database.sqlite', { namespace: 'users' });
const cache = new Keyv('sqlite://path/to/database.sqlite', { namespace: 'cache' });
// `users` and `cache` can share the same storage without key collisions."}Support for Multiple Backends
Keyv can be used with various storage backends like Redis, MongoDB, SQLite, and more.
{"const Keyv = require('keyv');
const keyv = new Keyv('redis://user:pass@localhost:6379');
keyv.set('foo', 'bar').then(() => keyv.get('foo').then(value => console.log(value)));
// This will use Redis as the storage backend."}TTL (Time to Live)
Automatically expire keys after a certain period of time.
{"const Keyv = require('keyv');
const keyv = new Keyv({ ttl: 10000 });
keyv.set('foo', 'expires in 10 seconds', 10000).then(() => setTimeout(() => keyv.get('foo').then(value => console.log(value)), 15000));
// Logs: undefined, since the key has expired after 10 seconds."}node-cache is an in-memory key-value store similar to keyv but does not support multiple backends. It is purely for in-memory storage with TTL support.
levelup is a wrapper for LevelDB. It provides a key-value store with a rich set of features. Unlike keyv, levelup is more complex and is designed specifically for LevelDB.
ioredis is a robust, performance-focused Redis client for Node.js. While keyv supports Redis as one of its backends, ioredis is dedicated solely to Redis and offers more advanced features specific to Redis.
memcached is a Node.js client for the memcached server. It is similar to keyv in providing a key-value cache but is specific to the memcached protocol and server.
Simple key-value storage with support for multiple backends
Keyv provides a consistent interface for key-value storage across multiple backends via storage adapters. It supports TTL based expiry, making it suitable as a cache or a persistent key-value store.
There are a few existing modules similar to Keyv, however Keyv is different because it:
Map APIBufferInstall Keyv.
npm install --save keyv
By default everything is stored in memory, you can optionally also install a storage adapter.
npm install --save @keyv/redis
npm install --save @keyv/mongo
npm install --save @keyv/sqlite
npm install --save @keyv/postgres
npm install --save @keyv/mysql
npm install --save @keyv/etcd
Create a new Keyv instance, passing your connection string if applicable. Keyv will automatically load the correct storage adapter.
const Keyv = require('keyv');
// One of the following
const keyv = new Keyv();
const keyv = new Keyv('redis://user:pass@localhost:6379');
const keyv = new Keyv('mongodb://user:pass@localhost:27017/dbname');
const keyv = new Keyv('sqlite://path/to/database.sqlite');
const keyv = new Keyv('postgresql://user:pass@localhost:5432/dbname');
const keyv = new Keyv('mysql://user:pass@localhost:3306/dbname');
const keyv = new Keyv('etcd://localhost:2379');
// Handle DB connection errors
keyv.on('error', err => console.log('Connection Error', err));
await keyv.set('foo', 'expires in 1 second', 1000); // true
await keyv.set('foo', 'never expires'); // true
await keyv.get('foo'); // 'never expires'
await keyv.delete('foo'); // true
await keyv.clear(); // undefined
You can namespace your Keyv instance to avoid key collisions and allow you to clear only a certain namespace while using the same database.
const users = new Keyv('redis://user:pass@localhost:6379', { namespace: 'users' });
const cache = new Keyv('redis://user:pass@localhost:6379', { namespace: 'cache' });
await users.set('foo', 'users'); // true
await cache.set('foo', 'cache'); // true
await users.get('foo'); // 'users'
await cache.get('foo'); // 'cache'
await users.clear(); // undefined
await users.get('foo'); // undefined
await cache.get('foo'); // 'cache'
Keyv uses json-buffer for data serialization to ensure consistency across different backends.
You can optionally provide your own serialization functions to support extra data types or to serialize to something other than JSON.
const keyv = new Keyv({ serialize: JSON.stringify, deserialize: JSON.parse });
Warning: Using custom serializers means you lose any guarantee of data consistency. You should do extensive testing with your serialisation functions and chosen storage engine.
The official storage adapters are covered by over 150 integration tests to guarantee consistent behaviour. They are lightweight, efficient wrappers over the DB clients making use of indexes and native TTLs where available.
| Database | Adapter | Native TTL |
|---|---|---|
| Redis | @keyv/redis | Yes |
| MongoDB | @keyv/mongo | Yes |
| SQLite | @keyv/sqlite | No |
| PostgreSQL | @keyv/postgres | No |
| MySQL | @keyv/mysql | No |
| Etcd | @keyv/etcd | Yes |
| Memcache | @keyv/memcache | Yes |
You can also use third-party storage adapters or build your own. Keyv will wrap these storage adapters in TTL functionality and handle complex types internally.
const Keyv = require('keyv');
const myAdapter = require('./my-storage-adapter');
const keyv = new Keyv({ store: myAdapter });
Any store that follows the Map api will work.
new Keyv({ store: new Map() });
For example, quick-lru is a completely unrelated module that implements the Map API.
const Keyv = require('keyv');
const QuickLRU = require('quick-lru');
const lru = new QuickLRU({ maxSize: 1000 });
const keyv = new Keyv({ store: lru });
The following are third-party storage adapters compatible with Keyv:
Keyv is designed to be easily embedded into other modules to add cache support. The recommended pattern is to expose a cache option in your modules options which is passed through to Keyv. Caching will work in memory by default and users have the option to also install a Keyv storage adapter and pass in a connection string, or any other storage that implements the Map API.
You should also set a namespace for your module so you can safely call .clear() without clearing unrelated app data.
Inside your module:
class AwesomeModule {
constructor(opts) {
this.cache = new Keyv({
uri: typeof opts.cache === 'string' && opts.cache,
store: typeof opts.cache !== 'string' && opts.cache,
namespace: 'awesome-module'
});
}
}
Now it can be consumed like this:
const AwesomeModule = require('awesome-module');
// Caches stuff in memory by default
const awesomeModule = new AwesomeModule();
// After npm install --save keyv-redis
const awesomeModule = new AwesomeModule({ cache: 'redis://localhost' });
// Some third-party module that implements the Map API
const awesomeModule = new AwesomeModule({ cache: some3rdPartyStore });
Keyv supports gzip and brotli compression. To enable compression, pass the compress option to the constructor.
const KeyvGzip = require('@keyv/compress-gzip');
const Keyv = require('keyv');
const keyvGzip = new KeyvGzip();
const keyv = new Keyv({ compression: KeyvGzip });
You can also pass a custom compression function to the compression option. Following the pattern of the official compression adapters.
Great! Keyv is designed to be easily extended. You can build your own compression adapter by following the pattern of the official compression adapters based on this interface:
interface CompressionAdapter {
async compress(value: any, options?: any);
async decompress(value: any, options?: any);
async serialize(value: any);
async deserialize(value: any);
}
In addition to the interface, you can test it with our compression test suite using @keyv/test-suite:
const {keyvCompresstionTests} = require('@keyv/test-suite');
const KeyvGzip = require('@keyv/compress-gzip');
keyvCompresstionTests(test, new KeyvGzip());
Returns a new Keyv instance.
The Keyv instance is also an EventEmitter that will emit an 'error' event if the storage adapter connection fails.
Type: String
Default: undefined
The connection string URI.
Merged into the options object as options.uri.
Type: Object
The options object is also passed through to the storage adapter. Check your storage adapter docs for any extra options.
Type: String
Default: 'keyv'
Namespace for the current instance.
Type: Number
Default: undefined
Default TTL. Can be overridden by specififying a TTL on .set().
Type: @keyv/compress-<compression_package_name>
Default: undefined
Compression package to use. See Compression for more details.
Type: Function
Default: JSONB.stringify
A custom serialization function.
Type: Function
Default: JSONB.parse
A custom deserialization function.
Type: Storage adapter instance
Default: new Map()
The storage adapter instance to be used by Keyv.
Type: String
Default: undefined
Specify an adapter to use. e.g 'redis' or 'mongodb'.
Keys must always be strings. Values can be of any type.
Set a value.
By default keys are persistent. You can set an expiry TTL in milliseconds.
Returns a promise which resolves to true.
Returns a promise which resolves to the retrieved value.
Type: Boolean
Default: false
If set to true the raw DB object Keyv stores internally will be returned instead of just the value.
This contains the TTL timestamp.
Deletes an entry.
Returns a promise which resolves to true if the key existed, false if not.
Delete all entries in the current namespace.
Returns a promise which is resolved when the entries have been cleared.
Iterate over all entries of the current namespace.
Returns a iterable that can be iterated by for-of loops. For example:
// please note that the "await" keyword should be used here
for await (const [key, value] of this.keyv.iterator()) {
console.log(key, value);
};
In this section of the documentation we will cover:
This package requires the following dependencies to run:
To contribute to this repository, start by setting up this project locally:
git cloneOnce the project is installed locally, you are ready to start up its services:
yarn command in the command prompt to install yarn.yarn bootstrap command to install any necessary dependencies.yarn test:services:start to start up this project's Docker container. The container will launch all services within your workspace.Once the project is running, you can execute a variety of commands. The root workspace and each subpackage contain a package.json file with a scripts field listing all the commands that can be executed from that directory. This project also supports native yarn, and docker commands.
Here, we'll cover the primary commands that can be executed from the root directory. Unless otherwise noted, these commands can also be executed from a subpackage. If executed from a subpackage, they will only affect that subpackage, rather than the entire workspace.
yarnThe yarn command installs yarn in the workspace.
yarn bootstrapThe yarn bootstrap command installs all dependencies in the workspace.
yarn test:services:startThe yarn test:services:start command starts up the project's Docker container, launching all services in the workspace. This command must be executed from the root directory.
yarn test:services:stopThe yarn test:services:stop command brings down the project's Docker container, halting all services. This command must be executed from the root directory.
yarn testThe yarn test command runs all tests in the workspace.
yarn cleanThe yarn clean command removes yarn and all dependencies installed by yarn. After executing this command, you must repeat the steps in Setting up your workspace to rebuild your workspace.
Now that you've set up your workspace, you're ready to contribute changes to the keyv repository.
yarn test command in the root directory.keyv repository and go the Pull Requests tab.keyv repository.If you need more information on the steps to create a pull request, you can find a detailed walkthrough in the Github documentation
MIT © Jared Wray
FAQs
Simple key-value storage with support for multiple backends
The npm package keyv receives a total of 6,368,674 weekly downloads. As such, keyv popularity was classified as popular.
We found that keyv demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.